Framebuffer attachment state. More...

#include <kanzi/core.ui/graphics2d/framebuffer.hpp>

Classes
struct	AttachmentData
	Optional attachment information. More...

class	AttachmentPoint
	Attachment point. More...

class	ResolveTarget
	Resolve target. More...

Public Member Functions
void	clearAttachements ()
	Clears all attachments and resolve targets.

const AttachmentPoint *	getColorAttachment (size_t index) const
	Gets the attachment at given index.

size_t	getColorAttachmentLimit () const
	Gets the number of color attachments.

RenderbufferSharedPtr	getColorRenderbuffer (size_t index) const
	Gets the color renderbuffer at given index, if one exists.

TextureSharedPtr	getColorResolveTarget (size_t index) const
	Gets the resolve target at given index.

TextureSharedPtr	getColorTexture (size_t index) const
	Gets the color texture at given index, if one exists.

AttachmentPoint *	getDepthStencilAttachment () const
	Gets the depth/stencil attachment.

RenderbufferSharedPtr	getDepthStencilRenderbuffer () const
	Gets the depth/stencil renderbuffer if one exists.

TextureSharedPtr	getDepthStencilResolveTarget () const
	Gets the depth or stencil resolve target, if one exists.

TextureSharedPtr	getDepthStencilTexture () const
	Gets the attached depth/stencil texture, if one exists.

size_t	getGPUMemoryUsage () const
	Gets the amount of GPU memory consumed by the framebuffer.

gfx::FrameBufferHandleGuard	getHandle () const
	Gets the graphics framebuffer handle.

NativeFramebufferHandle	getNativeHandle () const
	Gets the native framebuffer handle.

RenderPassArchetypeSharedPtr	getRenderPassArchetype () const
	Gets the graphics framebuffer handle.

bool	hasAttachedDepthTarget () const
	Indicates whether or not the framebuffer has an attachment with depth.

void	invalidate ()
	Invalidates the current framebuffer state.

bool	removeColorAttachment (size_t index)
	Clears the color attachment at index.

bool	removeDepthStencilAttachment ()
	Clears the depth/stencil attachment.

bool	resolveColorMSAA (Renderer &renderer, size_t index)
	Resolves first color renderbuffer MSAA into a texture attached to another framebuffer.

bool	resolveDepthMSAA (Renderer &renderer)
	Resolves the depth renderbuffer MSAA into a texture attached to another framebuffer.

bool	resolveMSAA (Renderer &renderer)
	Resolves MSAA into a texture attached to another framebuffer.

bool	setColorAttachment (size_t index, const Renderbuffer::CreateInfo &createInfo, string_view name)
	Sets the color attachment at index.

bool	setColorAttachment (size_t index, const RenderbufferSharedPtr &renderbuffer)
	Sets the color attachment at index.

bool	setColorAttachment (size_t index, const TextureSharedPtr &texture)
	Sets the color attachment at index.

bool	setColorAttachment (size_t index, const TextureSharedPtr &texture, size_t faceIndex)
	Sets the color attachment at index.

bool	setColorAttachment (size_t index, const TextureSharedPtr &texture, size_t faceIndex, size_t mipmapLevel)
	Sets the color attachment at index.

bool	setColorResolveTarget (size_t index, const TextureSharedPtr &texture)
	Sets the color resolve target at index.

bool	setDepthStencilAttachment (const Renderbuffer::CreateInfo &createInfo, string_view name)
	Sets the depth/stencil attachment.

bool	setDepthStencilAttachment (const RenderbufferSharedPtr &renderbuffer)
	Sets the depth/stencil attachment.

bool	setDepthStencilAttachment (const TextureSharedPtr &texture)
	Sets the depth/stencil attachment.

bool	setDepthStencilAttachment (const TextureSharedPtr &texture, size_t faceIndex)
	Sets the depth/stencil attachment.

bool	setDepthStencilAttachment (const TextureSharedPtr &texture, size_t faceIndex, size_t mipmapLevel)
	Sets the depth/stencil attachment.

bool	setDepthStencilResolveTarget (const TextureSharedPtr &texture)
	Sets the color resolve target at index.

void	setHandle (gfx::FrameBufferHandleGuard handle)
	Updates the framebuffer to use an explicit Kanzi graphics frame buffer handle.

void	setRenderPassArchetype (RenderPassArchetypeSharedPtr archetype)
	Sets the render pass archetype for the frame buffer.

void	swapAttachment (Texture &oldTexture, Texture &newTexture)
	Replaces the reference in an AttachmentPoint with the newTexture, if the reference is to the oldTexture.

bool	update (Renderer &renderer)
	Updates the framebuffer state.

Static Public Member Functions
static unique_ptr< Framebuffer >	create (string_view name)
	Creates a framebuffer.

Protected Member Functions
void	colorLimitDecrementCheck ()
	If the last color elements were cleared, decrement the color limit.

void	ensureAttachmentData ()
	Ensure that the AttachmentData is allocated.

	Framebuffer (string_view name)
	Default constructor.

bool	markColorAttachmentDirty (size_t index, bool dirty)
	Potentially mark a color attachment (and the framebuffer dirty).

Protected Attributes
unique_ptr< AttachmentData >	m_attachmentData
	Optional attachment information.

bool	m_dirty
	Flag for indicating the attachments have changed.

gfx::FrameBufferHandleGuard	m_handle
	Handle for the framebuffer object.

string	m_name
	Name of the framebuffer.

RenderPassArchetypeSharedPtr	m_renderPassArchetype
	RenderPass Archetype.

Detailed Description

Framebuffer attachment state.

Handles the attachment state for a framebuffer that combines multiple textures and renderbuffers into one render context.

Framebuffer is not a GPUResource, so for calculating total GPU memory and invalidating the state, it must be owned by another GPU resource.

Framebuffer class is intended for internal use by other Kanzi subsystems controlling rendering. It can also be used manually:

    // Create two individual render target textures.
    Texture::CreateInfoRenderTarget createInfo1(512, 384, GraphicsFormatR8G8B8A8_UNORM);
    Texture::CreateInfoRenderTarget createInfo2(512, 384, GraphicsFormatR8_UNORM);
    TextureSharedPtr texture1 = Texture::create(domain, createInfo1, "color target 1");
    TextureSharedPtr texture2 = Texture::create(domain, createInfo2, "color target 2");
 
    // Create a framebuffer.
    FramebufferPtr framebuffer = Framebuffer::create("test framebuffer");
 
    // Set the textures into the color attachments.
    framebuffer->setColorAttachment(0u, texture1);
    framebuffer->setColorAttachment(1u, texture2);
 
    // Recreate the framebuffer based on the state.
    framebuffer->update(*renderer);

Since: Kanzi 4.0.0 Framebuffer no longer inherits GPUResource.; Kanzi 4.0.0 removed attachTarget, clear, destroyOverride, getDepthTexture, invalidateOverride, isDeployedOverride, recreateFramebuffer, reloadOverride, updateColorAttachment, updateDepthAttachment. updateDepthStencilAttachment functions;; Kanzi 4.0.0 removed m_depthStencilRenderbuffer and m_depthTexture fields.; Kanzi 4.0.0 moved m_colorAttachments and m_drawBufferCount into optional m_attachmentData.

Constructor & Destructor Documentation

◆ Framebuffer()

kanzi::Framebuffer::Framebuffer ( string_view name )

explicitprotected

Default constructor.

Parameters

name	Name of the framebuffer.

Since: Kanzi 4.0.0 removed the domain parameter.

Member Function Documentation

◆ create()

static unique_ptr< Framebuffer > kanzi::Framebuffer::create ( string_view name )

inlinestatic

Creates a framebuffer.

Returns: Framebuffer pointer.

Parameters

name	Framebuffer name.

Since: Kanzi 4.0.0

◆ invalidate()

void kanzi::Framebuffer::invalidate ( )

Invalidates the current framebuffer state.

Since: Kanzi 4.0.0

◆ update()

bool kanzi::Framebuffer::update ( Renderer & renderer )

Updates the framebuffer state.

Needs to be done if the attachments have changed.

Parameters

renderer Renderer to use for the update.

Returns: If the framebuffer status was valid and was updated true, false otherwise.

Since: Kanzi 4.0.0 removed colorTexture, colorRenderbuffer, depthTexture and depthStencilRenderbuffer functions.

◆ setColorAttachment() [1/5]

bool kanzi::Framebuffer::setColorAttachment	(	size_t	index,
		const Renderbuffer::CreateInfo &	createInfo,
		string_view	name )

Sets the color attachment at index.

If the index is out of range, nothing is assigned.

Parameters

index	Index to set to.
createInfo	Renderbuffer create info
name	Name of the renderbuffer.

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setColorAttachment() [2/5]

bool kanzi::Framebuffer::setColorAttachment	(	size_t	index,
		const RenderbufferSharedPtr &	renderbuffer )

Sets the color attachment at index.

If the index is out of range, nothing is assigned.

Parameters

index	Index to set to.
renderbuffer	Renderbuffer to set

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setColorAttachment() [3/5]

bool kanzi::Framebuffer::setColorAttachment	(	size_t	index,
		const TextureSharedPtr &	texture,
		size_t	faceIndex,
		size_t	mipmapLevel )

Sets the color attachment at index.

If the index is out of range, nothing is assigned.

Parameters

index	Index to set to.
texture	Texture to set.
faceIndex	Attachment face index.
mipmapLevel	Attachment mipmap level.

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setColorAttachment() [4/5]

bool kanzi::Framebuffer::setColorAttachment	(	size_t	index,
		const TextureSharedPtr &	texture,
		size_t	faceIndex )

inline

Sets the color attachment at index.

Mipmap level is set to 0.

Parameters

index	Index to set to.
faceIndex	Attachment face index.
texture	Texture to set.

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setColorAttachment() [5/5]

bool kanzi::Framebuffer::setColorAttachment	(	size_t	index,
		const TextureSharedPtr &	texture )

inline

Sets the color attachment at index.

Face index is set to 0. Mipmap level is set to 0.

Parameters

index	Index to set to.
texture	Texture to set.

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ removeColorAttachment()

bool kanzi::Framebuffer::removeColorAttachment ( size_t index )

Clears the color attachment at index.

Updates the number of active color attachments.

Parameters

index Index to clear.

Returns: If the clear had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setColorResolveTarget()

bool kanzi::Framebuffer::setColorResolveTarget	(	size_t	index,
		const TextureSharedPtr &	texture )

Sets the color resolve target at index.

Parameters

index	Index to set to.
texture	Texture to set.

Returns: If the assignment had an effect and the framebuffer is dirty, true, otherwise false.

◆ setDepthStencilAttachment() [1/5]

bool kanzi::Framebuffer::setDepthStencilAttachment	(	const Renderbuffer::CreateInfo &	createInfo,
		string_view	name )

Sets the depth/stencil attachment.

Parameters

createInfo	Renderbuffer create info
name	Name of the renderbuffer.

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setDepthStencilAttachment() [2/5]

bool kanzi::Framebuffer::setDepthStencilAttachment ( const RenderbufferSharedPtr & renderbuffer )

Sets the depth/stencil attachment.

Parameters

renderbuffer Renderbuffer to set

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setDepthStencilAttachment() [3/5]

bool kanzi::Framebuffer::setDepthStencilAttachment	(	const TextureSharedPtr &	texture,
		size_t	faceIndex,
		size_t	mipmapLevel )

Sets the depth/stencil attachment.

Parameters

texture	Texture to set.
faceIndex	Attachment face index.
mipmapLevel	Attachment mipmap level.

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setDepthStencilAttachment() [4/5]

bool kanzi::Framebuffer::setDepthStencilAttachment	(	const TextureSharedPtr &	texture,
		size_t	faceIndex )

inline

Sets the depth/stencil attachment.

Mipmap level is set to 0.

Parameters

texture	Texture to set.
faceIndex	Attachment face index.

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setDepthStencilAttachment() [5/5]

bool kanzi::Framebuffer::setDepthStencilAttachment ( const TextureSharedPtr & texture )

inline

Sets the depth/stencil attachment.

Face index is set to 0. Mipmap level is set to 0.

Parameters

texture Texture to set.

Returns: If the assignment had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ removeDepthStencilAttachment()

bool kanzi::Framebuffer::removeDepthStencilAttachment ( )

Clears the depth/stencil attachment.

Returns: If the clear had an effect and the framebuffer is dirty true, false otherwise.

Since: Kanzi 4.0.0

◆ setDepthStencilResolveTarget()

bool kanzi::Framebuffer::setDepthStencilResolveTarget ( const TextureSharedPtr & texture )

Sets the color resolve target at index.

Parameters

texture Texture to set.

Returns: If the assignment had an effect and the framebuffer is dirty, true, otherwise false.

Since: Kanzi 4.0.0

◆ clearAttachements()

void kanzi::Framebuffer::clearAttachements ( )

Clears all attachments and resolve targets.

After calling this function, the framebuffer is ready for reuse

Since: Kanzi 4.0.0

◆ resolveColorMSAA()

bool kanzi::Framebuffer::resolveColorMSAA	(	Renderer &	renderer,
		size_t	index )

Resolves first color renderbuffer MSAA into a texture attached to another framebuffer.

Parameters

renderer	Renderer to use for resolve.
index	Index of the color attachment to resolve.

Returns: If a resolve happened true, false otherwise.

Since: Kanzi 4.0.0

◆ resolveDepthMSAA()

bool kanzi::Framebuffer::resolveDepthMSAA ( Renderer & renderer )

Resolves the depth renderbuffer MSAA into a texture attached to another framebuffer.

Parameters

renderer Renderer to use for resolve.

Returns: If a resolve happened true, false otherwise.

Since: Kanzi 4.0.0

◆ resolveMSAA()

bool kanzi::Framebuffer::resolveMSAA ( Renderer & renderer )

Resolves MSAA into a texture attached to another framebuffer.

What to resolve is determined from the target framebuffer.

Parameters

renderer Renderer to use for resolve.

Returns: If a resolve happened true, false otherwise.

Since: Kanzi 4.0.0

◆ getGPUMemoryUsage()

size_t kanzi::Framebuffer::getGPUMemoryUsage ( ) const

Gets the amount of GPU memory consumed by the framebuffer.

Only renderbuffers created by the framebuffer are calculated. Renderbuffers and textures assigned from outside own their own memory.

Returns: Amount of GPU memory owned by the framebuffer.

Since: Kanzi 4.0.0

◆ getHandle()

gfx::FrameBufferHandleGuard kanzi::Framebuffer::getHandle ( ) const

inline

Gets the graphics framebuffer handle.

Returns: Framebuffer handle.

Since: Kanzi 4.0.0

◆ setHandle()

void kanzi::Framebuffer::setHandle ( gfx::FrameBufferHandleGuard handle )

Updates the framebuffer to use an explicit Kanzi graphics frame buffer handle.

Parameters

handle The Kanzi graphics framebuffer handle.

Since: Kanzi 4.0.0

◆ getNativeHandle()

NativeFramebufferHandle kanzi::Framebuffer::getNativeHandle ( ) const

inline

Gets the native framebuffer handle.

This function is deprecated.

Returns: Native handle ID.

◆ setRenderPassArchetype()

void kanzi::Framebuffer::setRenderPassArchetype ( RenderPassArchetypeSharedPtr archetype )

inline

Sets the render pass archetype for the frame buffer.

Parameters

archetype The render pass archetype

Since: Kanzi 4.0.0

◆ getRenderPassArchetype()

RenderPassArchetypeSharedPtr kanzi::Framebuffer::getRenderPassArchetype ( ) const

inline

Gets the graphics framebuffer handle.

Returns: Framebuffer handle.

Since: Kanzi 4.0.0

◆ getColorAttachment()

const AttachmentPoint * kanzi::Framebuffer::getColorAttachment ( size_t index ) const

inline

Gets the attachment at given index.

Parameters

index Index to access.

Returns: Reference to attachment point at given index or nullptr if out of range.

Since: Kanzi 3.9.0; Kanzi 4.0.0 changed the type of the return value to const AttachmentPoint*.

◆ getColorAttachmentLimit()

size_t kanzi::Framebuffer::getColorAttachmentLimit ( ) const

inline

Gets the number of color attachments.

This number does not imply actual count of color attachments or mean there are no gaps in the array. The number implies the current maximum number of color attachments, supposing pointers have not expired.

Returns: Number of active color attachments.

Since: Kanzi 4.0.0 renamed from getDrawBufferCount.

◆ getColorRenderbuffer()

RenderbufferSharedPtr kanzi::Framebuffer::getColorRenderbuffer ( size_t index ) const

inline

Gets the color renderbuffer at given index, if one exists.

Parameters

index Index to access.

Returns: Renderbuffer or nullptr.

Since: Kanzi 4.0.0

◆ getColorTexture()

TextureSharedPtr kanzi::Framebuffer::getColorTexture ( size_t index ) const

inline

Gets the color texture at given index, if one exists.

Parameters

index Index to access.

Returns: Texture or nullptr.

◆ getColorResolveTarget()

TextureSharedPtr kanzi::Framebuffer::getColorResolveTarget ( size_t index ) const

inline

Gets the resolve target at given index.

Parameters

index Index to access.

Returns: Resolve target at given index or nullptr.

Since: Kanzi 4.0.0

◆ getDepthStencilAttachment()

AttachmentPoint * kanzi::Framebuffer::getDepthStencilAttachment ( ) const

inline

Gets the depth/stencil attachment.

The attachment may not be valid.

Returns: Reference to the depth attachment.

Since: Kanzi 4.0.0

◆ getDepthStencilRenderbuffer()

RenderbufferSharedPtr kanzi::Framebuffer::getDepthStencilRenderbuffer ( ) const

inline

Gets the depth/stencil renderbuffer if one exists.

Returns: Renderbuffer or nullptr.

Since: Kanzi 3.9.0

◆ getDepthStencilTexture()

TextureSharedPtr kanzi::Framebuffer::getDepthStencilTexture ( ) const

inline

Gets the attached depth/stencil texture, if one exists.

Returns: Texture or nullptr.

Since: Kanzi 4.0.0

◆ getDepthStencilResolveTarget()

TextureSharedPtr kanzi::Framebuffer::getDepthStencilResolveTarget ( ) const

inline

Gets the depth or stencil resolve target, if one exists.

Returns: Depth or stencil resolve texture or nullptr.

Since: Kanzi 4.0.0

◆ hasAttachedDepthTarget()

bool kanzi::Framebuffer::hasAttachedDepthTarget ( ) const

inline

Indicates whether or not the framebuffer has an attachment with depth.

Returns: If a depth attachment exists true, false otherwise.

Since: Kanzi 3.9.0

◆ swapAttachment()

void kanzi::Framebuffer::swapAttachment	(	Texture &	oldTexture,
		Texture &	newTexture )

Replaces the reference in an AttachmentPoint with the newTexture, if the reference is to the oldTexture.

This is called when the Texture itself has been swapped, and therefore references internal to Framebuffer should be updated to point to the same texture.

Parameters

oldTexture	The old texture to be updated.
newTexture	The new texture to use.

Since: Kanzi 4.0.0

◆ ensureAttachmentData()

void kanzi::Framebuffer::ensureAttachmentData ( )

inlineprotected

Ensure that the AttachmentData is allocated.

Since: Kanzi 4.0.0

◆ markColorAttachmentDirty()

bool kanzi::Framebuffer::markColorAttachmentDirty	(	size_t	index,
		bool	dirty )

inlineprotected

Potentially mark a color attachment (and the framebuffer dirty).

Called when a color attachment is set.

Parameters

index	Color attachment modified.
dirty	The dirty flag.

Returns: Pass through the dirty flag.

Since: Kanzi 4.0.0

◆ colorLimitDecrementCheck()

void kanzi::Framebuffer::colorLimitDecrementCheck ( )

inlineprotected

If the last color elements were cleared, decrement the color limit.

Member Data Documentation

◆ m_name

string kanzi::Framebuffer::m_name

protected

Name of the framebuffer.

◆ m_handle

gfx::FrameBufferHandleGuard kanzi::Framebuffer::m_handle

protected

Handle for the framebuffer object.

◆ m_renderPassArchetype

RenderPassArchetypeSharedPtr kanzi::Framebuffer::m_renderPassArchetype

protected

RenderPass Archetype.

◆ m_dirty

bool kanzi::Framebuffer::m_dirty

protected

Flag for indicating the attachments have changed.

If set, update()

Since: Kanzi 4.0.0

◆ m_attachmentData

unique_ptr<AttachmentData> kanzi::Framebuffer::m_attachmentData

mutableprotected

Optional attachment information.

Since: Kanzi 4.0.0 replacement for m_colorAttachments and m_drawBufferCount.

The documentation for this class was generated from the following file:

kanzi/core.ui/graphics2d/framebuffer.hpp

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Framebuffer()

Member Function Documentation

◆ create()

◆ invalidate()

◆ update()

◆ setColorAttachment() [1/5]

◆ setColorAttachment() [2/5]

◆ setColorAttachment() [3/5]

◆ setColorAttachment() [4/5]

◆ setColorAttachment() [5/5]

◆ removeColorAttachment()

◆ setColorResolveTarget()

◆ setDepthStencilAttachment() [1/5]

◆ setDepthStencilAttachment() [2/5]

◆ setDepthStencilAttachment() [3/5]

◆ setDepthStencilAttachment() [4/5]

◆ setDepthStencilAttachment() [5/5]

◆ removeDepthStencilAttachment()

◆ setDepthStencilResolveTarget()

◆ clearAttachements()

◆ resolveColorMSAA()

◆ resolveDepthMSAA()

◆ resolveMSAA()

◆ getGPUMemoryUsage()

◆ getHandle()

◆ setHandle()

◆ getNativeHandle()

◆ setRenderPassArchetype()

◆ getRenderPassArchetype()

◆ getColorAttachment()

◆ getColorAttachmentLimit()

◆ getColorRenderbuffer()

◆ getColorTexture()

◆ getColorResolveTarget()

◆ getDepthStencilAttachment()

◆ getDepthStencilRenderbuffer()

◆ getDepthStencilTexture()

◆ getDepthStencilResolveTarget()

◆ hasAttachedDepthTarget()

◆ swapAttachment()

◆ ensureAttachmentData()

◆ markColorAttachmentDirty()

◆ colorLimitDecrementCheck()

Member Data Documentation

◆ m_name

◆ m_handle

◆ m_renderPassArchetype

◆ m_dirty

◆ m_attachmentData